Add browser MP3 cleanse integration & rollout plan#6
Closed
ChrisAdamsdevelopment wants to merge 1 commit into
Closed
Add browser MP3 cleanse integration & rollout plan#6ChrisAdamsdevelopment wants to merge 1 commit into
ChrisAdamsdevelopment wants to merge 1 commit into
Conversation
Reviewer's GuideAdds a single documentation file describing a phased plan and architecture for integrating a browser-based MP3 metadata cleanse flow into the existing SpectraCleanse client, including UX guidance, KPIs, QA checklist, risks, and rollout strategy, with no code changes to the app itself. Sequence diagram for the new browser MP3 cleanse and server fallback flowsequenceDiagram
actor User
participant BrowserClient
participant MetadataUtils
participant SEOApi as Backend_API_generate_seo
participant ProcessApi as Backend_API_process
User->>BrowserClient: UploadFile(file)
BrowserClient->>MetadataUtils: readFileMetadata(file)
MetadataUtils-->>BrowserClient: metadata, provenanceIndicators
BrowserClient->>BrowserClient: UpdateContextTab(metadata)
User->>BrowserClient: ClickGenerateAISEOPayload()
BrowserClient->>SEOApi: POST /api/generate-seo (fileId, authToken)
SEOApi-->>BrowserClient: seoPayload
BrowserClient->>BrowserClient: UpdateSEOPayloadTab(seoPayload)
User->>BrowserClient: ChooseQuickCleanseBrowser()
alt FileIsMP3AndFeatureFlagEnabled
BrowserClient->>MetadataUtils: writeMP3Metadata(file, seoPayload)
MetadataUtils-->>BrowserClient: cleansedFile
BrowserClient->>BrowserClient: UpdateAnalysisTab(provenanceRisk)
User->>BrowserClient: ClickDownloadProcessedFile()
BrowserClient-->>User: Download(cleansedFile)
else NonMP3OrFlagDisabled
User->>BrowserClient: ChooseFullServerCleanse()
BrowserClient->>ProcessApi: POST /api/process (file, seoPayload, authToken)
ProcessApi-->>BrowserClient: processedFile, forensicReport, usageHeaders
BrowserClient->>BrowserClient: UpdateAnalysisTab(forensicReport)
BrowserClient->>BrowserClient: UpdateUsageFromHeaders(usageHeaders)
User->>BrowserClient: ClickDownloadProcessedFile()
BrowserClient-->>User: Download(processedFile)
end
Class diagram for planned client-side cleanse flow and utilitiesclassDiagram
class BrowserClientApp {
+bool featureEnableBrowserMP3Cleanse
+File currentFile
+SEOData currentSEOPayload
+AnalysisData currentAnalysis
+void onFileUpload(file)
+void generateSEO()
+void handleCleanse(useBrowser)
+void updateContextTab(metadata)
+void updateSEOTab(seoPayload)
+void updateAnalysisTab(analysis)
+void downloadProcessedFile()
}
class MetadataUtils {
+Metadata readFileMetadata(file)
+File writeMP3Metadata(file, metadata)
+ProvenanceRisk assessProvenanceRisk(metadata, filename)
}
class FeatureFlagConfig {
+bool enableBrowserMP3Cleanse
+bool isBrowserCleanseEnabledForFile(file)
}
class SEOApiClient {
+SEOData generateSEO(fileId, authToken)
}
class ProcessApiClient {
+ProcessResult processMedia(file, seoPayload, authToken)
}
class UsageTracker {
+int remainingCredits
+void updateFromHeaders(headers)
}
class TabsController {
+void showContextTab()
+void showSEOPayloadTab()
+void showAnalysisTab()
+void persistSessionLogs(logEntries)
}
class DownloadManager {
+string currentObjectUrl
+void createDownloadUrl(file)
+void revokeObjectUrl()
}
BrowserClientApp --> MetadataUtils : uses
BrowserClientApp --> FeatureFlagConfig : reads
BrowserClientApp --> SEOApiClient : calls
BrowserClientApp --> ProcessApiClient : calls
BrowserClientApp --> UsageTracker : updates
BrowserClientApp --> TabsController : controls
BrowserClientApp --> DownloadManager : manages
MetadataUtils ..> DownloadManager : sharesFileReferences
class Metadata {
+string title
+string artist
+string album
+map tags
}
class SEOData {
+string title
+string description
+string keywords
}
class AnalysisData {
+Metadata metadata
+ProvenanceRisk provenanceRisk
+string recommendedAction
}
class ProcessResult {
+File processedFile
+AnalysisData analysis
+Headers responseHeaders
}
class ProvenanceRisk {
+string level
+string[] indicators
}
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- In the implementation plan, where you recommend browser cleanses not counting toward monthly usage, it would help to explicitly capture the alternate path (if product later decides they should count) so engineers know exactly where to plug in usage updates on the client and server paths.
- Consider adding concrete request/response examples or field contracts for
/api/generate-seoand/api/process(e.g., required headers, expected SEO payload shape, error payload schema) so the future client wiring work has less ambiguity and better alignment with backend expectations. - Since the plan introduces new browser metadata dependencies and local ID3 writing, it might be useful to briefly call out any security/privacy constraints (e.g., no remote calls from those libs, supported file size limits, handling of corrupted files) to guide library selection and hardening work in Phase 4.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In the implementation plan, where you recommend browser cleanses not counting toward monthly usage, it would help to explicitly capture the alternate path (if product later decides they should count) so engineers know exactly where to plug in usage updates on the client and server paths.
- Consider adding concrete request/response examples or field contracts for `/api/generate-seo` and `/api/process` (e.g., required headers, expected SEO payload shape, error payload schema) so the future client wiring work has less ambiguity and better alignment with backend expectations.
- Since the plan introduces new browser metadata dependencies and local ID3 writing, it might be useful to briefly call out any security/privacy constraints (e.g., no remote calls from those libs, supported file size limits, handling of corrupted files) to guide library selection and hardening work in Phase 4.
## Individual Comments
### Comment 1
<location path="docs/mp3-browser-integration-plan.md" line_range="30" />
<code_context>
+
+### Keep
+- New browser cleanse state machine and decoupled download flow.
+- Dark themed tabbed UI (`Context`, `SEO Payload`, `Analysis`).
+- Memory-safe object URL lifecycle.
+
</code_context>
<issue_to_address>
**nitpick (typo):** Consider hyphenating "Dark-themed" as a compound adjective.
Because it precedes “UI,” the hyphenated form is the standard and clearer spelling.
Suggested implementation:
```
- Dark-themed tabbed UI (`Context`, `SEO Payload`, `Analysis`).
```
If this phrasing appears elsewhere in the document (e.g., headings or other bullets), you may also want to standardize them to "Dark-themed" for consistency.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
|
|
||
| ### Keep | ||
| - New browser cleanse state machine and decoupled download flow. | ||
| - Dark themed tabbed UI (`Context`, `SEO Payload`, `Analysis`). |
There was a problem hiding this comment.
nitpick (typo): Consider hyphenating "Dark-themed" as a compound adjective.
Because it precedes “UI,” the hyphenated form is the standard and clearer spelling.
Suggested implementation:
- Dark-themed tabbed UI (`Context`, `SEO Payload`, `Analysis`).
If this phrasing appears elsewhere in the document (e.g., headings or other bullets), you may also want to standardize them to "Dark-themed" for consistency.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e791ea8014
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ### User value | ||
| 1. **Speed:** MP3 users get immediate local cleanse with no upload required. | ||
| 2. **Trust:** Local/offline-friendly flow reduces privacy concerns. | ||
| 3. **Control:** Explicit two-step process (`Generate SEO` -> `Cleanse`) and manual download button. |
There was a problem hiding this comment.
The plan defines an explicit Generate SEO -> Cleanse sequence, which makes local MP3 cleansing depend on /api/generate-seo availability; if that endpoint is down, unauthenticated, or quota-limited, users lose the browser-only path even though local ID3 writing could still succeed. This conflicts with the stated goals of speed/privacy for MP3 users and creates an avoidable single point of failure in the primary flow.
Useful? React with 👍 / 👎.
| 3. **Analysis tab clarity** | ||
| - Split into cards: file info, extracted tags, provenance risk, recommended action. | ||
| 4. **Trust copy** | ||
| - For browser path: “processed locally in your browser; nothing uploaded.” |
There was a problem hiding this comment.
The proposed trust copy says “nothing uploaded,” but this same plan routes Generate AI SEO Payload through authenticated POST /api/generate-seo, which transmits user-provided prompt content to the backend. Keeping this absolute wording is likely to mislead privacy-sensitive users; the copy should distinguish “audio file stays local” from metadata/text sent for SEO generation.
Useful? React with 👍 / 👎.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closed as superseded planning work. The implementation path landed through PR #8 for stabilization and PR #9 for browser MP3 quick cleanse integration.